home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 2000 October / Software of the Month - Ultimate Collection Shareware 277.iso / pc / PROGRAMS / UTILITY / WINLINUX / DATA1.CAB / programs_-_usrdoc / TIN / INTERNAL.{_4 < prev    next >
Text File  |  1999-09-17  |  4KB  |  130 lines
  1. I/O in tin (updated 05/01/98)
  2. ----------
  3.  
  4. All critical I/O, be it NNTP data or not, should be done with
  5. tin_fgets() This handles data formatting, removes any trailing \n and \r
  6. and deals with timeouts, reconnections and user aborts.
  7.  
  8. It supports the use of 'q' to abort the operation and 'Q' to exit tin
  9. without error recovery.
  10.  
  11. tin_errno will be set to !0 to flag errors. Currently the only
  12. supported error is 'user aborted with q'.
  13.  
  14. Closing NNTP data files should be done with TIN_FCLOSE(fp) as the NNTP
  15. socket should be kept open, whereas local spool fd's must be closed.
  16. TIN_FCLOSE() takes care of this.
  17.  
  18. If you wish to quit reading an NNTP stream, then call drain_buffer(fp) to
  19. clear out any pending data on NNTP socket.
  20.  
  21. nntp_command(command, valid_response, rest_of_data) should be used for
  22. sending all generic NNTP command. It returns an fd to the open stream
  23. for reading the rest of the data.
  24.  
  25.  
  26. Example of a typical exchange:
  27.  
  28. if (nntp_command ("GROUP comp.thing", OK_GROUP, NULL) != NULL) {
  29.  
  30.     while ((ptr = tin_fgets(buff, sizeof(buff), nntp_rd_fd)) != NULL)
  31.         process_data(ptr);
  32.  
  33.     if (tin_errno != 0)
  34.         return (read_error);
  35.  
  36. }
  37.  
  38.  
  39.  
  40. Hashing in tin (updated 05/01/98)
  41. --------------
  42.  
  43. All the main arrays in tin are dynamically managed by functions in memory.c
  44. They are preallocated to an initial size and then grown if the high
  45. water mark is exceeded.
  46.  
  47. The main structures are:
  48.  
  49. active[]
  50. An array of all the groups in the active file
  51.  
  52. arts[]
  53. This is an array of the article headers for the current group. Only headers
  54. present in the overview (NOV) database are stored.
  55.  
  56. base[]
  57. An array of integers that represent the index in arts[] of the current
  58. root article for each displayed thread.
  59.  
  60. group_hash[]
  61. active[] is hashed for faster access. An entry of -1 denotes no group at
  62. this hashnode, >= 0 denotes an index into active[]
  63. Multiple groups on one node are chained via the .next field (another index
  64. ptr to active[])
  65.  
  66. my_group[]
  67. List of integer pointers into active[]
  68. These are the groups that actually appear on the selection screen
  69.  
  70. msgids[]
  71. Hashed array of all the individual message-ids in arts[]
  72. All the Message-ID and Reference headers are broken down and stored here.
  73. They are linked together by parent, sibling and child pointers
  74.  
  75. table[]
  76. Hash of the key text headers from the articles, to save space and speed up
  77. searches and compares.
  78.  
  79.  
  80. The functions that manipulate the above include:
  81.  
  82. active.c:
  83.     read_news_active_file() populates active[] using psGrpAdd()
  84.  
  85.  
  86. art.c:
  87.     Many of the overview headers are stored with hash_str()
  88.     base[] is populated by find_base()
  89.  
  90. hashstr.c:
  91.     hash_str() Hashes text strings
  92.  
  93.     In the article header, the following text is hashed:
  94.         From: (including full name if supplied)
  95.         Archive-name:
  96.         Subject:
  97.  
  98.  
  99. list.c:
  100.     init_group_hash() clears group_hash[]
  101.     find_group_index() returns index of group in active[]
  102.     psGrpFind() returns a pointer to a group in active[]
  103.     psGrpAdd() adds a group into active[] and hashes it in group_hash[]
  104.     hash_groupname() returns hash key for a group
  105.         This is also used to hash the actual filenames written
  106.         in ~/.tin/.news (when not using NNTP)
  107.         There is experimental code here for a (presumably)
  108.         improved hash function that was never completed.
  109.  
  110. main.c:
  111.     Just the initializers for hashing
  112.  
  113.  
  114. memory.c:
  115.     Dynamic array management.
  116.     hash_reclaim() - free up table[] which holds the
  117.     text cache
  118.  
  119.  
  120. refs.c:
  121.     Handling for msgids[]
  122.     When threading, each msgid in the hash has a pointer back to
  123.     its article header in arts[] or ART_UNAVAILABLE if the article is not
  124.     available
  125.  
  126.  
  127. select.c:
  128.     my_group_add() adds a group to my_group[]
  129.     my_group_find() returns the index of a group in my_group[]
  130.